Summary

Add support for the Claude Agent SDK as a new provider in instructor, enabling structured outputs with the SDK's native JSON schema validation capabilities.

Key Features

• New from_claude_agent_sdk() factory function - Creates an Instructor configured for Claude Agent SDK
• CLAUDE_AGENT_SDK mode - New mode for structured outputs via the SDK
• Automatic schema conversion - Converts Pydantic models to JSON schemas for output_format
• Built-in retry support - Handles validation errors with context-aware retries
• Message format conversion - Automatically converts instructor's message format to prompts

Usage Example

from instructor import from_claude_agent_sdk
from pydantic import BaseModel
import anyio

class User(BaseModel):
  name: str
  age: int

async def main():
  client = from_claude_agent_sdk()

user = await client.create(
  response_model=User,
  messages=[{"role": "user", "content": "Extract: John is 25 years old"}]
)
print(f"Name: {user.name}, Age: {user.age}")

anyio.run(main)

Files Added/Modified

New files:

• instructor/providers/claude_agent_sdk/__init__.py
• instructor/providers/claude_agent_sdk/client.py
• instructor/providers/claude_agent_sdk/utils.py
• examples/claude_agent_sdk/run.py
• docs/integrations/claude_agent_sdk.md

Modified files:

• instructor/__init__.py - Conditional import when claude_agent_sdk is available
• instructor/mode.py - Added CLAUDE_AGENT_SDK mode
• instructor/utils/providers.py - Added CLAUDE_AGENT_SDK provider
• instructor/processing/response.py - Added handler mappings

Benefits

• Uses the Claude Agent SDK's native JSON schema validation for guaranteed compliance
• Familiar instructor interface for existing users
• No subprocess overhead (unlike CLI-based approaches)
• Production-ready with proper error handling and retries

Fixes #1640

Adds Claude Agent SDK as a new provider to the instructor framework, enabling structured outputs with JSON schema validation.

• Behavior:
  • Adds from_claude_agent_sdk() factory function in client.py to create an Instructor for Claude Agent SDK.
  • Introduces CLAUDE_AGENT_SDK mode in mode.py for structured outputs.
  • Implements automatic schema conversion from Pydantic models to JSON schemas.
  • Includes built-in retry support for validation errors.
  • Converts instructor's message format to prompts automatically.
• Files:
  • Adds instructor/providers/claude_agent_sdk/__init__.py, client.py, and utils.py for Claude Agent SDK integration.
  • Modifies instructor/__init__.py for conditional import of from_claude_agent_sdk.
  • Updates instructor/processing/response.py to include handler mappings for Claude Agent SDK.
• Documentation and Examples:
  • Adds docs/integrations/claude_agent_sdk.md for integration guide.
  • Provides examples/claude_agent_sdk/run.py for usage examples.
• Misc:
  • Adds CLAUDE_AGENT_SDK to Provider enum in providers.py.

^{This description was created by for 49d9d6f. You can customize this summary. It will automatically update as commits are pushed.}